/**
 * @file nst_msg.h
 * @brief 通用消息队列框架
 * @date 2025-11-03
 */

#ifndef NST_MSG_H
#define NST_MSG_H

#ifdef __cplusplus
extern "C" {
#endif

/* Includes ------------------------------------------------------------------*/
#include <stdint.h>
#include <stdbool.h>

/* Exported constants --------------------------------------------------------*/

#define NST_MSG_NAME_LEN     16     /* 队列名称最大长度 */

/* Exported types ------------------------------------------------------------*/

/**
 * @brief 消息队列结构
 */
typedef struct
{
    char name[NST_MSG_NAME_LEN];    /* 队列名称（用于调试） */
    uint8_t *buffer;                /* 队列缓冲区指针 */
    uint16_t element_size;          /* 单个元素大小（字节） */
    uint16_t queue_size;            /* 队列容量（元素个数） */
    volatile uint16_t head;         /* 队列头指针 */
    volatile uint16_t tail;         /* 队列尾指针 */
} nst_msg_queue_t;

/* Exported functions prototypes ---------------------------------------------*/

/**
 * @brief 初始化消息队列
 * @param queue 队列对象
 * @param name 队列名称（用于调试）
 * @param buffer 预分配的缓冲区指针
 * @param element_size 单个消息元素的大小（字节）
 * @param queue_size 队列容量（元素个数）
 */
void nst_msg_init(nst_msg_queue_t *queue, const char *name, uint8_t *buffer,
                  uint16_t element_size, uint16_t queue_size);

/**
 * @brief 非阻塞入队（中断安全）
 * @param queue 队列对象
 * @param msg 消息指针
 * @retval true 成功, false 队列已满
 */
bool nst_msg_enqueue(nst_msg_queue_t *queue, const void *msg);

/**
 * @brief 非阻塞出队（中断安全）
 * @param queue 队列对象
 * @param msg 消息输出指针
 * @retval true 成功, false 队列为空
 */
bool nst_msg_dequeue(nst_msg_queue_t *queue, void *msg);

/**
 * @brief 检查队列是否为空
 * @param queue 队列对象
 * @retval true 为空, false 不为空
 */
bool nst_msg_is_empty(const nst_msg_queue_t *queue);

/**
 * @brief 检查队列是否已满
 * @param queue 队列对象
 * @retval true 已满, false 未满
 */
bool nst_msg_is_full(const nst_msg_queue_t *queue);

/**
 * @brief 获取队列剩余空间（元素个数）
 * @param queue 队列对象
 * @retval 剩余空间大小
 */
uint16_t nst_msg_remaining(const nst_msg_queue_t *queue);

#ifdef __cplusplus
}
#endif

#endif /* NST_MSG_H */

/******************************** 文件结束 *********************************/
